/**
 * MCP工具接口定义
 * @Author: 莫若省
 * @date: 2025/9/2
 * 描述一个符合MCP协议的工具模块必须实现的标准接口，
 * 用于在MCP服务中注册和使用工具。
 */

// @ts-ignore
import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/dist/cjs/shared/protocol.js";
import { ZodRawShape } from "zod";
// @ts-ignore
import { ServerNotification } from "@modelcontextprotocol/sdk/dist/esm/types.js";
// @ts-ignore
import { CallToolResult, ServerRequest } from "@modelcontextprotocol/sdk/dist/cjs/types.js";

/**
 * MCP工具接口
 *
 * 定义了一个工具模块必须包含的属性和方法，
 * 用于在MCP协议的服务工具的注册和使用。
 */
export interface MCPToolInterface {
    /**
     * 工具名称
     * @description 必须是唯一的标识符，用于在MCP协议中调用该工具
     * @example "date_calculator"
     */
    name: string,

    /**
     * 工具描述
     * @description 简要说明工具的功能，用于文档和帮助信息
     * @example "日期计算工具，支持各种日期格式转换和计算"
     */
    description: string,

    /**
     * 工具参数定义
     * @description 使用Zod库定义工具的参数结构和验证规则
     * @type {ZodRawShape} Zod原始形状定义
     * @example
     * {
     *   date: z.string().describe("日期字符串")
     * }
     * zod库安装时务必使用3.x版本，否则会导致参数无法识别
     */
    prams: ZodRawShape,

    /**
     * 工具回调函数
     * @description 工具的核心业务逻辑实现
     * @param args 调用工具时传入的参数对象
     * @param extra 请求的额外信息，包含请求上下文等
     * @returns 返回工具调用结果或Promise
     *
     * @type {Function}
     * @param {Object} args - 工具参数对象
     * @param {RequestHandlerExtra<ServerRequest, ServerNotification>} extra - 请求额外信息
     * @returns {CallToolResult | Promise<CallToolResult>} 工具调用结果
     *
     * @example
     * async (args, extra) => {
     *   return { content: [{ text: "处理结果", type: "text" }] };
     * }
     */
    cb: (
        args: { [p: string]: any },
        extra: RequestHandlerExtra<ServerRequest, ServerNotification>
    ) => (CallToolResult | Promise<CallToolResult>),
}

/**
 * 类型说明：
 *
 * 1. RequestHandlerExtra - 请求处理器的额外信息，包含请求上下文等
 * 2. ServerRequest - 服务端请求对象
 * 3. ServerNotification - 服务端通知类型
 * 4. CallToolResult - 工具调用结果类型
 * 5. ToolAnnotations - 工具注解信息
 *
 * 这些类型来自@modelcontextprotocol/sdk，提供了MCP协议的核心类型定义。
 */